Settings are the knobs that are used to tweak and tune the performance of the system. Conceptually, settings are exposed as read/write or write-only attributes of JMX. Some of the examples of settings are pool size, maximum queue length and so on.

Types of Settings

Based upon their implementation, Settings are catogorized into the following types:

Cold settings

A cold setting is the setting in which the change will be applied to the setting only after a restart of the Service Container. This kind of setting cannot be applied in the run-time execution of the process.

Hot Settings

A Hot setting is the setting in which the change is persistent through the settings persister and the related setter Web service operation is invoked. When defining a hot setting, the setter Web service operation must be provided so that the setting will be applied in the running process.

While defining, the setting can be selected as read/write or write-only by choosing the appropriate defineXxxSetting Web service operation. Usually, Write-only settings are used for passwords.

Settings persistence

The settings persistence handler stores and retrieves the settings as needed. The settings are retrieved either from wcp.properties or the bussoapprocessorconfiguration in LDAP.

LDAPBusConfigSettingsPersistenceHandler supports retrieving and storing the settings in the configuration file of the LDAP bus service container. The changes in the settings are logged under the category com.eibus.management.SettingDefinition.

Defining a setting

A collection of settings is required to define the settings. The settings collection can be obtained through the Web service operation{{getSettingsCollection}} of the Managed Component. If no parameter is passed, the default settings collection is returned.

Defining a hot setting

A hot setting requires a setter Web service operation that is invoked when the setting value is changed. The name of the setter Web service operation should be defined in the format set<< propertyImplName>>.
For example, the setter Web service operation for the propertyImplName minConcurrentWorkers is given below:

public void setMinConcurrentWorkers(int minConcurrentWorkers)

This setter Web service operation gets called before the value of the setting is stored in LDAP.
The following sample taken from com.eibus.util.threadpool.Dispatcher depicts the definition of a hot setting:

ISettingsCollection settings =  m_managedComponent.getSettingsCollection();

If (settings != null)
{
// There is a settings collection defined,
// so we can define settings.
int minConcurrentWorkers = (Integer)settings.defineHotSetting(
"minConcurrentWorkers",
Messages.MIN_CONCURRENT_WORKERS_COUNTER_DESC,
"minConcurrentWorkers",
this,
null,
m_minConcurrentWorkers,
0,
Integer.MAX_VALUE);
}

Defining a cold setting

A cold setting does not require any setter Web service operation. The following sample from com.eibus.util.threadpool.Dispatcher describes the definition of a cold setting:

ISettingsCollection settings = m_managedComponent.getSettingsCollection();
If (settings \!= null)
{
// There is a settings collection defined,
// so we can define settings.
int maxPendingWorks = (Integer) settings.defineColdSetting(
"maxPendingWorks",
Messages.MAX_PENDING_WORKS_COUNTER_DESC,
null,
defaultMaxQueueSize,
0,
Integer.MAX_VALUE);
}

Defining a write-only setting

The following sample from com.eibus.applicationconnector.sql.DBConnectionPool describes the definition of write-only setting:

ISettingsCollection settings = m_managedComponent.getSettingsCollection();
If (settings != null)
{
// There is a settings collection defined,
// so we can define settings.
String password = (String) settings.
defineWriteOnlyColdSetting("password",
Messages.DB_PASSWORD_DESC,
(String) legacyNames.get("password"),
String.class);
}

Defining a complex-type setting

While defining a complex setting, ensure that the name of the complex-type setting is <jmxApplications>. Each <settingValue> represents an instance of the collection of settings and <name> is used to identify the value of the setting in the list. It is recommended that the name of the attribute should be unique in structure.
Consider a service container with the bussoapprocessorconfiguration given below.

<configurations ...
:
:
<configuration implementation="com.eibus.applicationconnector.management.ManagementConnector" htmfile="/cordys/wcp/admin/applicationconnector/management.htm">
*<jmxApplications>*
*<settingValue>*
*<name>Test</name>*
*<hostname>cnd0825</hostname>*
*<port>1099</port>*
*<jmxuser>hewa</jmxuser>*
*<jmxpassword>aGV3YQ==</jmxpassword>*
*</settingValue>*
*<settingValue>*
*<name>AnotherTest</name>*
*<hostname>cnd0825</hostname>*
*<port>1099</port>*
*<jmxuser>hewa</jmxuser>*
*<jmxpassword>aGV3YQ==</jmxpassword>*
*</settingValue>*
*</jmxApplications>*
</configuration>
:
:
</configurations>

In the code, jmxApplications is exposed as a complex setting that returns NodeObject.

ISettingsCollection settings = m_managedComponent.getSettingsCollection();

If (settings != null)
{
// There is a settings collection defined,
// so we can define settings.
NodeObject jmxApplications = (NodeObject)
settings.defineColdSetting(
"jmxApplications",
Messages.JMX_APPLICATIONS_DESC,
null,
NodeObject.class);
}

Legacy Settings

The settings for bussoapprocessorconfiguration of the Service Container has been modified after CU2 release. To support the previous version of the settings, a legacy property has been framed. For new settings, the legacyProperty is not applicable.
According to the new framework, the properties related to a service container must exist as child elements to <configurations>.
For example, the settings such as spyPublish, cancelReplyInterval should be added as child elements to the configurations node.

<configurations>
<spyPublish>false</spyPublish>
<cancelReplyInterval>30000</cancelReplyInterval>
<configuration implementation="com.eibus.applicationconnector.xmlstore.XMLStore"/>
</configurations>
All the application connector related settings must exist as child elements to <configurations><configuration>.
For example the setting {{root}} is related to {{xmlstore}} application connector and is present as child element to configuration node.
<configurations>
<spyPublish>false</spyPublish>
<configuration implementation="com.eibus.applicationconnector.xmlstore.XMLStore">
<root>D:\Program Files\Cordys\WCP\XMLStore</root>
</configuration>
</configurations>

The sample code given below describes the procedure to define the settings that contain legacy Settings.

// Old configuration
<configurations cancelReplyInterval="30000">
<configuration implementation="com.eibus.applicationconnector.xmlstore.XMLStore"/>
</configurations>
// New configuration
<configurations>
<cancelReplyInterval>30000</cancelReplyInterval>
<configuration implementation="com.eibus.applicationconnector.xmlstore.XMLStore"/>
</configurations>

Defining a setting with legacy property

The below sample code which is derived from com.eibus.soap.Processor describes the definition of a setting with legacy property:

ISettingsCollection settings = m_managedComponent.getSettingsCollection();
long cancelReplyInterval = ((Long)
settings.defineHotSetting("cancelReplyInterval",
Messages.CANCEL_REPLY_DESC,   "cancelReplyInterval",
requestMonitor,
LDAPBusConfigSettingsLegacySettingProvider.PREFIX +
"<configurations>@cancelReplyInterval",
new Long(30000),
new Long(0),
new Long(3600000))).longValue();

The settings provider reads the legacy properties from LDAP and WCP properties. In the above sample, the suffix LDAPBusConfigSettingsLegacySettingProvider.PREFIX +"<configurations>@cancelReplyInterval" represents that the settings are being read from LDAP, that is, the bussoapprocessorconfiguration of the service container.
In the above code, the symbol '@' indicates that the property exists as an attribute. As the setting cancelReplyInterval is defined using the managed component of the service container, the settings provider searches for the attribute cancelReplyInterval for the element <configurations>.
For example, if the legacy property is given as LDAPBusConfigSettingsLegacySettingProvider.PREFIX + "<configurations><cancelReplyInterval> the settings provider searches for the element <cancelReplyInterval> as a child to <configurations>.
Initially, the settings provider searches for the settings in the new structure; if the settings are not found, it will perform a search in the legacy path.